home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / JFC.bin / ListSelectionModel.java < prev    next >
Text File  |  1998-06-30  |  9KB  |  267 lines
  1. /*
  2.  * @(#)ListSelectionModel.java    1.9 98/01/30
  3.  * 
  4.  * Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  */
  20.  
  21. package com.sun.java.swing;
  22.  
  23. import com.sun.java.swing.event.*;
  24.  
  25. /**
  26.  * This interface represents the current state of the 
  27.  * selection for any of the components that display a 
  28.  * list of values with stable indices.  The selection is 
  29.  * modeled as a set of intervals, each interval represents
  30.  * a contiguous range of selected list elements.
  31.  * The methods for modifying the set of selected intervals
  32.  * all take a pair of indices, index0 and index1, that represent
  33.  * a closed interval, i.e. the interval includes both index0 and
  34.  * index1.
  35.  * 
  36.  * @version 1.9 01/30/98
  37.  * @author Hans Muller
  38.  * @author Philip Milne
  39.  * @see DefaultListSelectionModel
  40.  */
  41.  
  42. public interface ListSelectionModel 
  43. {
  44.     /**
  45.      * A value for the selectionMode property: select one list index
  46.      * at a time.
  47.      * 
  48.      * @see #setSelectionMode
  49.      */
  50.     int SINGLE_SELECTION = 0;
  51.  
  52.     /**
  53.      * A value for the selectionMode property: select one contiguous
  54.      * range of indices at a time.
  55.      * 
  56.      * @see #setSelectionMode
  57.      */
  58.     int SINGLE_INTERVAL_SELECTION = 1;
  59.  
  60.     /**
  61.      * A value for the selectionMode property: select one or more 
  62.      * contiguous ranges of indices at a time.
  63.      * 
  64.      * @see #setSelectionMode
  65.      */
  66.     int MULTIPLE_INTERVAL_SELECTION = 2;
  67.  
  68.  
  69.     /** 
  70.      * Change the selection to be between index0 and index1 inclusive.
  71.      * If this represents a change to the current selection, then
  72.      * notify each ListSelectionListener. Note that index0 doesn't have
  73.      * to be less than or equal to index1.  
  74.      * 
  75.      * @param index0 one end of the interval.
  76.      * @param index1 other end of the interval
  77.      * @see #addListSelectionListener
  78.      */
  79.     void setSelectionInterval(int index0, int index1);
  80.  
  81.  
  82.     /** 
  83.      * Change the selection to be the set union of the current selection
  84.      * and the indices between index0 and index1 inclusive.  If this represents 
  85.      * a change to the current selection, then notify each 
  86.      * ListSelectionListener. Note that index0 doesn't have to be less
  87.      * than or equal to index1.  
  88.      * 
  89.      * @param index0 one end of the interval.
  90.      * @param index1 other end of the interval
  91.      * @see #addListSelectionListener
  92.      */
  93.     void addSelectionInterval(int index0, int index1);
  94.  
  95.  
  96.     /** 
  97.      * Change the selection to be the set difference of the current selection
  98.      * and the indices between index0 and index1 inclusive.  If this represents 
  99.      * a change to the current selection, then notify each 
  100.      * ListSelectionListener.  Note that index0 doesn't have to be less
  101.      * than or equal to index1.  
  102.      * 
  103.      * @param index0 one end of the interval.
  104.      * @param index1 other end of the interval
  105.      * @see #addListSelectionListener
  106.      */
  107.     void removeSelectionInterval(int index0, int index1);
  108.  
  109.  
  110.     /**
  111.      * Returns the first selected index or -1 if the selection is empty.
  112.      */
  113.     int getMinSelectionIndex();
  114.  
  115.  
  116.     /**
  117.      * Returns the last selected index or -1 if the selection is empty.
  118.      */
  119.     int getMaxSelectionIndex();
  120.  
  121.  
  122.     /** 
  123.      * Returns true if the specified index is selected.
  124.      */
  125.     boolean isSelectedIndex(int index);
  126.  
  127.     
  128.     /**
  129.      * Return the first index argument from the most recent
  130.      * call to setSelectionInterval() or addSelectionInterval().
  131.      * The most recent index0 is considered the "anchor" and the most recent
  132.      * index1 is considered the "lead".  Some interfaces display these
  133.      * indices specially, e.g. Windows95 displays the lead index with a 
  134.      * dotted yellow outline.
  135.      * 
  136.      * @see #getLeadSelectionIndex
  137.      * @see #setSelectionInterval
  138.      * @see #addSelectionInterval
  139.      */
  140.     int getAnchorSelectionIndex();
  141.  
  142.  
  143.     /**
  144.      * Set the anchor selection index. 
  145.      * 
  146.      * @see #getAnchorSelectionIndex
  147.      */
  148.     void setAnchorSelectionIndex(int index);
  149.  
  150.  
  151.     /**
  152.      * Return the second index argument from the most recent
  153.      * call to setSelectionInterval() or addSelectionInterval().
  154.      * 
  155.      * @see #getAnchorSelectionIndex
  156.      * @see #setSelectionInterval
  157.      * @see #addSelectionInterval
  158.      */
  159.     int getLeadSelectionIndex();
  160.  
  161.     /**
  162.      * Set the lead selection index. 
  163.      * 
  164.      * @see #getLeadSelectionIndex
  165.      */
  166.     void setLeadSelectionIndex(int index);
  167.  
  168.     /**
  169.      * Change the selection to the empty set.  If this represents
  170.      * a change to the current selection then notify each ListSelectionListener.
  171.      * 
  172.      * @see #addListSelectionListener
  173.      */
  174.     void clearSelection();
  175.  
  176.     /**
  177.      * Returns true if no indices are selected.
  178.      */
  179.     boolean isSelectionEmpty();
  180.     
  181.     /** 
  182.      * Insert length indices beginning before/after index.  This is typically 
  183.      * called to sync the selection model with a corresponding change
  184.      * in the data model.
  185.      */
  186.     void insertIndexInterval(int index, int length, boolean before);
  187.  
  188.     /** 
  189.      * Remove the indices in the interval index0,index1 (inclusive) from
  190.      * the selection model.  This is typically called to sync the selection
  191.      * model width a corresponding change in the data model.
  192.      */
  193.     void removeIndexInterval(int index0, int index1);
  194.  
  195.     /**
  196.      * This property is true if upcoming changes to the value
  197.      * of the model should be considered a single event. For example
  198.      * if the model is being updated in response to a user drag,
  199.      * the value of the valueIsAdjusting property will be set to true
  200.      * when the drag is initiated and be set to false when
  201.      * the drag is finished.  This property allows listeners to 
  202.      * to update only when a change has been finalized, rather
  203.      * than always handling all of the intermediate values.
  204.      * 
  205.      * @param valueIsAdjusting The new value of the property.
  206.      * @see #getValueIsAdjusting
  207.      */
  208.     void setValueIsAdjusting(boolean valueIsAdjusting);
  209.  
  210.     /**
  211.      * @return The value of the valueIsAdjusting property.
  212.      * @see #setValueIsAdjusting
  213.      */
  214.     boolean getValueIsAdjusting();
  215.  
  216.     /**
  217.      * The following selectionMode values are allowed:
  218.      * <ul>
  219.      * <li> <code>SINGLE_SELECTION</code> 
  220.      *   Only one list index can be selected at a time.  In this
  221.      *   mode the setSelectionInterval and addSelectionInterval 
  222.      *   methods are equivalent, and only the second index
  223.      *   argument (the "lead index") is used.
  224.      * <li> <code>SINGLE_INTERVAL_SELECTION</code>
  225.      *   One contiguous index interval can be selected at a time.
  226.      *   In this mode setSelectionInterval and addSelectionInterval 
  227.      *   are equivalent.
  228.      * <li> <code>MULTIPLE_INTERVAL_SELECTION</code>
  229.      *   In this mode, there's no restriction on what can be selected.
  230.      * </ul>
  231.      * 
  232.      * @see #getSelectionMode
  233.      */
  234.     void setSelectionMode(int selectionMode);
  235.  
  236.     /**
  237.      * @return The value of the selectionMode property.
  238.      * @see #setSelectionMode
  239.      */
  240.     int getSelectionMode();
  241.  
  242.     /**
  243.      * Add a listener to the list that's notified each time a change
  244.      * to the selection occurs.
  245.      * 
  246.      * @param l the ListSelectionListener
  247.      * @see #removeListSelectionListener
  248.      * @see #setSelectionInterval
  249.      * @see #addSelectionInterval
  250.      * @see #removeSelectionInterval
  251.      * @see #clearSelection
  252.      * @see #insertIndexInterval
  253.      * @see #removeIndexInterval
  254.      */  
  255.     void addListSelectionListener(ListSelectionListener x);
  256.  
  257.     /**
  258.      * Remove a listener from the list that's notified each time a 
  259.      * change to the selection occurs.
  260.      * 
  261.      * @param l the ListSelectionListener
  262.      * @see #addListSelectionListener
  263.      */  
  264.     void removeListSelectionListener(ListSelectionListener x);
  265. }
  266.  
  267.